home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1994 November: Tool Chest / Dev.CD Nov 94.toast / Tool Chest / QuickDraw GX / QuickDraw GX Info / QuickDraw GX Interfaces / Interfaces & Libraries / Pascal Interfaces & Libraries / Pascal Interfaces / Collections.p next >
Encoding:
Text File  |  1994-03-24  |  12.0 KB  |  429 lines  |  [TEXT/MPS ]
  1. { ------------------------------------------------------------------------------
  2.  
  3.     FILENAME
  4.         Collections.p
  5.  
  6.     DESCRIPTION
  7.         This file contains all of the public data structures, constants, and 
  8.         function declarations for the Collection Manager.
  9.  
  10.     COPYRIGHT
  11.         Copyright © Apple Computer, Inc. 1989, 1990, 1991, 1992, 1993
  12.         All rights reserved. 
  13.  
  14. ------------------------------------------------------------------------------- }
  15.  
  16.  
  17. {$IFC UNDEFINED UsingIncludes}
  18. {$SETC UsingIncludes := 0}
  19. {$ENDC}
  20.  
  21. {$IFC NOT UsingIncludes}
  22.     UNIT Collections;
  23.     INTERFACE
  24. {$ENDC}
  25.  
  26. {$IFC UNDEFINED UsingCollections}
  27. {$SETC UsingCollections := 1}
  28.  
  29. {$I+}
  30. {$SETC CollectionsIncludes := UsingIncludes}
  31. {$SETC UsingIncludes := 1}
  32. {$IFC UNDEFINED UsingTypes}
  33. {$I $$Shell(PInterfaces)Types.p}
  34. {$ENDC}
  35. {$SETC UsingIncludes := CollectionsIncludes}
  36.  
  37. { Constants }
  38.  
  39.  
  40. CONST
  41. { Collection Manager Gestalt Selector... }
  42.  
  43.     gestaltCollectionMgrVersion = 'cltn';
  44.  
  45. { Collection Manager Error Result Codes... }
  46.  
  47.     collectionItemLockedErr = -5750;
  48.     collectionItemNotFoundErr = -5751;
  49.     collectionIndexRangeErr = -5752;
  50.     collectionVersionErr = -5753;
  51.  
  52.  
  53. { Convenience constants for calls to functions which optionally return values... }
  54.  
  55.     dontWantTag = 0;
  56.     dontWantId = 0;
  57.     dontWantSize = 0;
  58.     dontWantAttributes = 0;
  59.     dontWantIndex = 0;
  60.     dontWantData = 0;
  61.  
  62.  
  63. { attributes bits }
  64.  
  65.     noCollectionAttributes = $00000000;            { no attributes bits set }
  66.     allCollectionAttributes = $FFFFFFFF;        { all attributes bits set }
  67.     userCollectionAttributes = $0000FFFF;        { user attributes bits }
  68.     defaultCollectionAttributes = $40000000;    { default attributes - unlocked, persistent }
  69.  
  70.  
  71. { 
  72.     Attribute bits 0 through 15 (entire low word) are reserved for use by the application.
  73.     Attribute bits 16 through 31 (entire high word) are reserved for use by the Collection Manager.
  74.     Only bits 31 (collectionLockBit) and 30 (collectionPersistenceBit) currently have meaning.
  75. }
  76.  
  77.  
  78.     collectionUser0Bit            = 0;
  79.     collectionUser1Bit            = 1;
  80.     collectionUser2Bit            = 2;
  81.     collectionUser3Bit            = 3;
  82.     collectionUser4Bit            = 4;
  83.     collectionUser5Bit            = 5;
  84.     collectionUser6Bit            = 6;
  85.     collectionUser7Bit            = 7;
  86.     collectionUser8Bit            = 8;
  87.     collectionUser9Bit            = 9;
  88.     collectionUser10Bit            = 10;
  89.     collectionUser11Bit            = 11;
  90.     collectionUser12Bit            = 12;
  91.     collectionUser13Bit            = 13;
  92.     collectionUser14Bit            = 14;
  93.     collectionUser15Bit            = 15;
  94.     
  95.     collectionReserved0Bit        = 16;
  96.     collectionReserved1Bit        = 17;
  97.     collectionReserved2Bit        = 18;
  98.     collectionReserved3Bit        = 19;
  99.     collectionReserved4Bit        = 20;
  100.     collectionReserved5Bit        = 21;
  101.     collectionReserved6Bit        = 22;
  102.     collectionReserved7Bit        = 23;
  103.     collectionReserved8Bit        = 24;
  104.     collectionReserved9Bit        = 25;
  105.     collectionReserved10Bit        = 26;
  106.     collectionReserved11Bit        = 27;
  107.     collectionReserved12Bit        = 28;
  108.     collectionReserved13Bit        = 29;
  109.     
  110.     collectionPersistenceBit    = 30;
  111.     collectionLockBit                = 31;
  112.  
  113.  
  114. { attribute masks }
  115.  
  116.     collectionUser0Mask            = $00000001;
  117.     collectionUser1Mask            = $00000002;
  118.     collectionUser2Mask            = $00000004;
  119.     collectionUser3Mask            = $00000008;
  120.     collectionUser4Mask            = $00000010;
  121.     collectionUser5Mask            = $00000020;
  122.     collectionUser6Mask            = $00000040;
  123.     collectionUser7Mask            = $00000080;
  124.     collectionUser8Mask            = $00000100;
  125.     collectionUser9Mask            = $00000200;
  126.     collectionUser10Mask            = $00000400;
  127.     collectionUser11Mask            = $00000800;
  128.     collectionUser12Mask            = $00001000;
  129.     collectionUser13Mask            = $00002000;
  130.     collectionUser14Mask            = $00004000;
  131.     collectionUser15Mask            = $00008000;
  132.  
  133.     collectionReserved0Mask            = $00010000;
  134.     collectionReserved1Mask            = $00020000;
  135.     collectionReserved2Mask            = $00040000;
  136.     collectionReserved3Mask            = $00080000;
  137.     collectionReserved4Mask            = $00100000;
  138.     collectionReserved5Mask            = $00200000;
  139.     collectionReserved6Mask            = $00400000;
  140.     collectionReserved7Mask            = $00800000;
  141.     collectionReserved8Mask            = $01000000;
  142.     collectionReserved9Mask            = $02000000;
  143.     collectionReserved10Mask        = $04000000;
  144.     collectionReserved11Mask        = $08000000;
  145.     collectionReserved12Mask        = $10000000;
  146.     collectionReserved13Mask        = $20000000;
  147.     collectionReserved14Mask        = $40000000;
  148.     collectionReserved15Mask        = $80000000;
  149.  
  150.     collectionPersistenceMask    = $40000000;        { mask for lock bit }
  151.     collectionLockMask            = $80000000;        { mask for lock bit }
  152.  
  153.  
  154. { the Collection Manager trap }
  155.  
  156.     collectionManagerTrap = $ABF6;
  157.  
  158.  
  159. { Types }
  160.  
  161.  
  162. TYPE
  163.  
  164.     PrivateCollectionRecord = LONGINT;
  165.     Collection = ^PrivateCollectionRecord;    { abstract data type for a collection }
  166.     CollectionTag = LONGINT;                    { collection member 4 byte tag }
  167.     CollectionTagPtr = ^CollectionTag;
  168.     CollectionFlattenProc = ProcPtr;
  169.     CollectionExceptionProc = ProcPtr;
  170.  
  171.  
  172. {
  173.     A CollectionFlattenProc should look like this:
  174.  
  175.     FUNCTION MyFlattenProc (size : LONGINT; data : UNIV Ptr; refCon : UNIV Ptr) : OSErr;
  176. }
  177.  
  178.  
  179. {
  180.     A CollectionExceptionProc should look like this:
  181.  
  182.     FUNCTION MyExceptionProc (aCollection : Collection; anErr : OSErr) : OSErr;
  183. }
  184.  
  185.  
  186. {*********************************************************************}
  187. { ***************            Public Interfaces            **********************}
  188. { ********************************************************************}
  189.  
  190.  
  191. FUNCTION NewCollection : Collection;
  192.     INLINE $7000,collectionManagerTrap;
  193.  
  194. PROCEDURE DisposeCollection (aCollection : Collection);
  195.     INLINE $7001,collectionManagerTrap;
  196.  
  197. FUNCTION CloneCollection (aCollection : Collection) : Collection;
  198.     INLINE $7002,collectionManagerTrap;
  199.  
  200. FUNCTION CountCollectionOwners (aCollection : Collection) : LONGINT;
  201.     INLINE $7003,collectionManagerTrap;
  202.  
  203. FUNCTION CopyCollection (srcCollection, dstCollection : Collection) : Collection;
  204.     INLINE $7004,collectionManagerTrap;
  205.  
  206. FUNCTION GetCollectionDefaultAttributes (aCollection : Collection) : LONGINT;
  207.     INLINE $7005,collectionManagerTrap;
  208.  
  209. PROCEDURE SetCollectionDefaultAttributes (aCollection : Collection;
  210.                                                         whichAttributes: LONGINT;
  211.                                                           newAttributes : LONGINT);
  212.     INLINE $7006,collectionManagerTrap;
  213.  
  214.  
  215. FUNCTION CountCollectionItems (aCollection : Collection) : LONGINT;
  216.     INLINE $7007,collectionManagerTrap;
  217.  
  218.  
  219. FUNCTION AddCollectionItem (aCollection : Collection;
  220.                                        tag : CollectionTag;
  221.                                       id : LONGINT;
  222.                                       itemSize : LONGINT;
  223.                                       pItemData : UNIV Ptr) : OSErr;
  224.     INLINE $7008,collectionManagerTrap;
  225.  
  226.  
  227. FUNCTION GetCollectionItem (aCollection : Collection;
  228.                                         tag : CollectionTag;
  229.                                         id : LONGINT;
  230.                                         pItemSize : LongIntPtr;
  231.                                         pItemData : UNIV Ptr) : OSErr;
  232.     INLINE $7009,collectionManagerTrap;
  233.  
  234.  
  235. FUNCTION RemoveCollectionItem (aCollection : Collection;
  236.                                          tag : CollectionTag;
  237.                                          id: LONGINT) : OSErr;
  238.     INLINE $700A,collectionManagerTrap;
  239.  
  240.  
  241. FUNCTION SetCollectionItemInfo (aCollection : Collection;
  242.                                              tag : CollectionTag;
  243.                                             id : LONGINT;
  244.                                               whichAttributes : LONGINT;
  245.                                             newAttributes : LONGINT) : OSErr;
  246.     INLINE $700B,collectionManagerTrap;
  247.  
  248.  
  249. FUNCTION GetCollectionItemInfo (aCollection : Collection;
  250.                                              tag : CollectionTag;
  251.                                             id : LONGINT;
  252.                                               pIndex : LongIntPtr;
  253.                                             pItemSize : LongIntPtr;
  254.                                               pAttributes : LongIntPtr) : OSErr;
  255.     INLINE $700C,collectionManagerTrap;
  256.  
  257.  
  258. FUNCTION ReplaceIndexedCollectionItem (aCollection : Collection;
  259.                                                            index : LONGINT;
  260.                                                         itemSize : LONGINT;
  261.                                                        pItemData : UNIV Ptr) : OSErr;
  262.     INLINE $700D,collectionManagerTrap;
  263.  
  264.  
  265. FUNCTION GetIndexedCollectionItem (aCollection : Collection;
  266.                                                   index : LONGINT;
  267.                                                  pItemSize : LongIntPtr;
  268.                                                 pItemData : UNIV Ptr) : OSErr;
  269.     INLINE $700E,collectionManagerTrap;
  270.  
  271.  
  272.  
  273. FUNCTION RemoveIndexedCollectionItem (aCollection : Collection;
  274.                                                   index : LONGINT) : OSErr;
  275.     INLINE $700F,collectionManagerTrap;
  276.  
  277.  
  278. FUNCTION SetIndexedCollectionItemInfo (aCollection : Collection;
  279.                                                         index : LONGINT;
  280.                                                         whichAttributes : LONGINT;
  281.                                                      newAttributes : LONGINT) : OSErr;
  282.     INLINE $7010,collectionManagerTrap;
  283.  
  284.  
  285. FUNCTION GetIndexedCollectionItemInfo (aCollection : Collection;
  286.                                                   index : LONGINT;
  287.                                                  pTag : CollectionTagPtr;
  288.                                                  pId : LongIntPtr;
  289.                                                   pItemSize : LongIntPtr;
  290.                                                  pAttributes : LongIntPtr) : OSErr;
  291.     INLINE $7011,collectionManagerTrap;
  292.  
  293.  
  294. FUNCTION CollectionTagExists (aCollection : Collection;
  295.                                         tag : CollectionTag) : Boolean;
  296.     INLINE $7012,collectionManagerTrap;
  297.  
  298.  
  299. FUNCTION CountCollectionTags (aCollection : Collection) : LONGINT;
  300.     INLINE $7013,collectionManagerTrap;
  301.  
  302.  
  303. FUNCTION GetIndexedCollectionTag (aCollection : Collection;
  304.                                              whichTag : LONGINT;
  305.                                              var tag : CollectionTag) : OSErr;
  306.     INLINE $7014,collectionManagerTrap;
  307.  
  308.  
  309. FUNCTION CountTaggedCollectionItems (aCollection : Collection;
  310.                                                  tag : CollectionTag) : LONGINT;
  311.     INLINE $7015,collectionManagerTrap;
  312.  
  313.  
  314. FUNCTION GetTaggedCollectionItem (aCollection : Collection;
  315.                                              tag : CollectionTag;
  316.                                              whichItem : LONGINT;
  317.                                              pItemSize : LongIntPtr;
  318.                                              pItemData : UNIV Ptr) : OSErr;
  319.     INLINE $7016,collectionManagerTrap;
  320.  
  321.  
  322. FUNCTION GetTaggedCollectionItemInfo (aCollection : Collection;
  323.                                                    tag : CollectionTag;
  324.                                                    whichItem : LONGINT;
  325.                                                   pID : LongIntPtr;
  326.                                                   pIndex : LongIntPtr;
  327.                                                    pItemSize : LongIntPtr;
  328.                                                    pAttributes : LongIntPtr) : OSErr;
  329.     INLINE $7017,collectionManagerTrap;
  330.  
  331.  
  332. PROCEDURE PurgeCollection (aCollection : Collection;
  333.                                     whichAttributes : LONGINT;
  334.                                     matchingAttributes : LONGINT);
  335.     INLINE $7018,collectionManagerTrap;
  336.  
  337.  
  338. PROCEDURE PurgeCollectionTag (aCollection : Collection;
  339.                                         tag : CollectionTag);
  340.     INLINE $7019,collectionManagerTrap;
  341.  
  342.  
  343. PROCEDURE EmptyCollection (aCollection : Collection);
  344.     INLINE $701A,collectionManagerTrap;
  345.  
  346.  
  347. FUNCTION FlattenCollection (aCollection : Collection;
  348.                                      flattenProc : CollectionFlattenProc;
  349.                                      refCon : UNIV Ptr) : OSErr;
  350.     INLINE $701B,collectionManagerTrap;
  351.  
  352.  
  353. FUNCTION FlattenPartialCollection (aCollection : Collection;
  354.                                                flattenProc : CollectionFlattenProc;
  355.                                                refCon : UNIV Ptr;
  356.                                               whichAttributes : LONGINT;
  357.                                               matchingAttributes : LONGINT) : OSErr;
  358.     INLINE $701C,collectionManagerTrap;
  359.  
  360.  
  361. FUNCTION UnflattenCollection (aCollection : Collection;
  362.                                         flattenProc: CollectionFlattenProc;
  363.                                         refCon : UNIV Ptr) : OSErr;
  364.     INLINE $701D,collectionManagerTrap;
  365.  
  366.  
  367. FUNCTION GetCollectionExceptionProc (aCollection : Collection) : CollectionExceptionProc;
  368.     INLINE $701E,collectionManagerTrap;
  369.  
  370.  
  371. PROCEDURE SetCollectionExceptionProc (aCollection : Collection;
  372.                                                   exceptionProc : CollectionExceptionProc);
  373.     INLINE $701F,collectionManagerTrap;
  374.  
  375.  
  376.  
  377. {**************************************************************************************}
  378. { Utility Routines for handle-based access...                                                        }
  379. {**************************************************************************************}
  380.  
  381.  
  382.  
  383. FUNCTION GetNewCollection (collectionID : INTEGER) : Collection;
  384.     INLINE $7020,collectionManagerTrap;
  385.  
  386.  
  387. FUNCTION AddCollectionItemHdl (aCollection : Collection;
  388.                                               tag : CollectionTag;
  389.                                               id : LONGINT;
  390.                                               hItemData : Handle) : OSErr;
  391.     INLINE $7021,collectionManagerTrap;
  392.  
  393.  
  394. FUNCTION GetCollectionItemHdl (aCollection : Collection;
  395.                                             tag : CollectionTag;
  396.                                             id : LONGINT;
  397.                                               hItemData : Handle) : OSErr;
  398.     INLINE $7022,collectionManagerTrap;
  399.  
  400.                           
  401. FUNCTION ReplaceIndexedCollectionItemHdl (aCollection : Collection;
  402.                                                                 index : LONGINT;
  403.                                                             hItemData : Handle) : OSErr;
  404.     INLINE $7023,collectionManagerTrap;
  405.  
  406.                                     
  407. FUNCTION GetIndexedCollectionItemHdl (aCollection : Collection;
  408.                                                        index : LONGINT;
  409.                                                         hItemData : Handle) : OSErr;
  410.     INLINE $7024,collectionManagerTrap;
  411.  
  412.                           
  413. FUNCTION FlattenCollectionToHdl (aCollection : Collection;
  414.                                             flattened : Handle) : OSErr;
  415.     INLINE $7025,collectionManagerTrap;
  416.  
  417.  
  418. FUNCTION UnflattenCollectionFromHdl (aCollection : Collection;
  419.                                                  flattened : Handle) : OSErr;
  420.     INLINE $7026,collectionManagerTrap;
  421.  
  422.  
  423.  
  424. {$ENDC}    { UsingCollections }
  425.  
  426. {$IFC NOT UsingIncludes}
  427.     END.
  428. {$ENDC}
  429.